Itential Docs & Guides | Drive Automation for Modern Networks

Search APIs

Operations Manager (OM) includes two new search APIs in release 2021.2.

Search API
`GET /operations-manager/jobs`
`GET /operations-manager/tasks`

Both of these new APIs include support for advanced search parameters through query parameters.

⚠ Note: The following documentation applies only to the two new APIs, not the /automations or /triggers APIs.

Basic Examples

To get all jobs whose name starts with the string 'Job name prefix' :

GET /operations-manager/jobs?starts-with[name]=Job name prefix

To get the IDs and names of all jobs started after November 18, 2021, use 2021-11-18 [YYYY-MM-DD date format]:

GET /operations-manager/jobs?include=_id,name&gt[metrics.start_time]=2021-11-18t23:59:59

Query Parameter Syntax

Operations Manager uses an object syntax to express operators and their relationship to the fields they operate on. For example, to get all documents that have a field equal to a particular value, use the following syntax:

equals[field]=value

This syntax allows the search API to accept multiple field conditions in a single request. Likewise, to get all the jobs whose name is Job name 1, and whose description is Job description 1, the follow request could be made:

GET /operations-manager/jobs?equals[name]=Job%20name%201&equals[description]=Job%20description%201

The API supports querying on nested properties within a document using dotted path notation. For example, to get all tasks which were started after 2021-11-18, the following request could be made:

GET /operations-manager/tasks?gt[metrics.start_time]=2021-11-18T23:59:59

Response Format

Operations Manager standardizes the top-level structure of all responses, both success and error, with the following fields:

Property	Description
message	This property contains a human readable message, and will always be populated with a string.
data	This property contains any data that is directly related to the request. This key will always be present; if it is not applicable to the request (as with error responses), it will be set to `null`.
metadata	This property contains any extra details on the response. When no metadata is available, this will be an empty object. This field is used in several places, including pagination information in search responses, as well as detailed reports on failed imports and input validation failures.

Example response

{
  "message": "Human readable message",
  "data": {
    "some": "data"
  },
  "metadata": {
    "some": "metadata"
  }
}

Search Operators

This section outlines the available search operators used to narrow the focus of a search query.

`equals`

The equals returns documents whose field exactly matches the specified value. The type of the field is known to Operations Manager, meaning there is no need for an API consumer to specify which fields should be interpreted as Dates, ObjectIds, booleans, etc. Operations Manager will interpret the value according to the structure of the document being queried.

Example

GET /operations-manager/jobs?equals[name]=JobName

`starts-with`, `ends-with`, and `contains`

These three related search operators return documents whose field either starts with, ends with, or contains the specified string.

Examples

GET /operations-manager/jobs?starts-with[name]=NamePrefix
GET /operations-manager/tasks?ends-with[name]=Suffix
GET /operations-manager/jobs?contains[description]=InternalString

Special note on `contains`

Specifically for the /jobs API, the description property has special behavior when queried with contains. When filtering over the description field on jobs, MongoDB text search syntax is supported. This allows efficient searching for complex expressions in the description field even when the jobs collection grows very large. Please refer to the MongoDB text search documentation for details on supported behavior.

`in` and `not-in`

The in operator accepts a comma-separated list of options, and returns documents whose field is exactly equal to one of the specified options.

For example, to get jobs whose name is either Name 1, Name 2, or Name 3, the following request could be used:

GET /operations-manager/jobs?in[name]=Name%201,Name%202,Name%203

The not-in operator also accepts a comma-separated list of options, and returns documents whose field is not equal to any of the specified options.

If the search value contains a comma, it is important to explicitly percent encode that comma (a comma is percent encoded to %2C), otherwise Operations Manager will interpret it as multiple options, rather than a single option with comma characters inside. For example, to search for jobs whose name is either Name,1 or Name,2, use the following request:

GET /operations-manager/jobs?in[name]=Name%2C1,Name%2C2

The in and not-in operator interpret the items in the option list according to the type of the specified field, as with the equals operator.

Examples

GET /operations-manager/jobs?in[name]=EitherThis,OrThis,OrMaybeThis
GET /operations-manager/tasks?not-in[description]=NotThis,OrThis

`gt`, `lt`, `gte`, and `lte`

These operators provide support for comparison operators in searches. Use gt for greater than comparisons, lt for less than, gte for greater than or equal to, and lte for less than or equal to.

The values provided to these operators are interpreted based on the type of the specified field, as with the equals, in, and not-in operators.

Examples

GET /operations-manager/jobs?gt[metrics.progress]=0.5
GET /operations-manager/jobs?lte[metrics.start_time]=2021-11-18T23:59:59

`q`

The ?q= query parameter exposes a way of doing more complex searches than are possible with other top-level query parameters.

To use it, express your query as a JSON object:

?equals[name]=my name&starts-with[description]=Some desc prefix

Which becomes:

{ "equals": { "name": "my name" }, "starts-with": { "description": "Some desc prefix" } }

Make sure to use encodeURLComponent to encode the JSON expression before using it. The advantage of this parameter is that it not only supports all top-level query parameters as described above, but also logical combinations of those parameters with and, or, and not.

Projection Parameters

Projection parameters are used to limit the fields returned in the API response. The fields returned may be specified either using an inclusive list with include, or an exclusive list with exclude.

⚠ When specifying an inclusive list, the _id field is implicitly included, even if it is not specified; to exclude it from the list, use &exclude=_id alongside the include expression to remove it.

`include`

The include parameter accepts a comma-delineated list of property names. This specifies the set of properties to include in the API response.

Example request

GET /operations-manager/jobs?include=name,description

Example response

Note the properties included in the data array.

{
  "message": "Successfully retrieved items",
  "data": [
    {
      "_id": "000000000000000000000000",
      "name": "Job 1",
      "description": "Job description 1"
    },
    {
      "_id": "111111111111111111111111",
      "name": "Job 2",
      "description": "Job description 2",
    }
  ],
  "metadata": {
    "skip": 0,
    "limit": 100,
    "nextPageSkip": null,
    "previousPageSkip": null,
    "total": 2,
    "currentPageSize": 2,
  }
}

Example request

Note the addition of &exclude=_id

GET /operations-manager/jobs?include=name,description&exclude=_id

Example response

{
  "message": "Successfully retrieved items",
  "data": [
    {
      "name": "Job 1",
      "description": "Job description 1"
    },
    {
      "name": "Job 2",
      "description": "Job description 2",
    }
  ],
  "metadata": {
    "skip": 0,
    "limit": 100,
    "nextPageSkip": null,
    "previousPageSkip": null,
    "total": 2,
    "currentPageSize": 2,
  }
}

Sort Parameters

Sort parameters arrange query results in a specified sequence (order) for any extracted data or list elements. Sorting is activated by ?sort=< field > and ?order=< -1 | 1 >.

Use both parameters to specify the sort order; in other words, they must be used together (cannot skip one).

order must be -1 or 1
sort must be a valid field path within the queried document type

When querying /jobs, you can provide:

?sort=metrics.start_time

⚠ But do not use:

?sort=metrics.some_other_field

The sort parameter must not be excluded from the resulting document with projection parameters.

Pagination Parameters

Most API endpoints that return a list of entities have some sort of pagination. Use the ?skip=< number > and ?limit=< number > parameters to limit the results returned by the query and control the paging of all documents returned in a result set.

skip and limit must be numbers
limit defaults to 100 and skip defaults to 0

Operations Manager

Help us improve by sending feedback...

On this page:

Search APIs

Search APIs

Basic Examples

Query Parameter Syntax

Response Format

Search Operators

equals

starts-with, ends-with, and contains

Special note on contains

in and not-in

gt, lt, gte, and lte

q

Projection Parameters

include

Sort Parameters

Pagination Parameters

`equals`

`starts-with`, `ends-with`, and `contains`

Special note on `contains`

`in` and `not-in`

`gt`, `lt`, `gte`, and `lte`

`q`

`include`